плохая документация в фронтенд проекте госзаказчика

— Лучше бы вообще не было этой документации, — сказал аналитик и ушел в отпуск, а потом и уволился. Так начался мой первый день на проекте для госзаказчика.

Меня взяли вторым фронтендером, и нужно было просто сверстать пару десятков форм, для заполнения разных документов: паспорта, снилс, свидетельство о рождении и т.п.

На онбординге мне дали ссылку на пространство в Confluence и я начал читать. Красиво. Много. Куча разных схемок и умных слов, значение которых я понимал достаточно отдаленно, так как был не в контексте. На первой странице висела плашка с парой десятков фамилий с заголовком «Согласовано». Документов в пространстве было так много, что я протыкав несколько так и не нашел ничего полезного для себя. Чем больше я погружался, тем меньше понимал, что вообще тут происходит и как нужно работать.

— Окей, надо просто решить что мне надо. Было бы здорово, пока выдаются доступы, посмотреть на описание АПИ и клиентский путь. — подумал я и начал копаться более осознанно.

Мне пришлось попросить коллег, чтобы они показали мне, где хранятся нужные мне артефакты. И я был в шоке. Во-первых, макетов не было вообще. Во-вторых, описание АПИ было сплошь из канцеляризмов, а описание пользовательских путей вообще отсутствовало, как и связи между параметрами с бекенда и интерфейсом.

Но настоящая боль началась позже. Код менялся каждый день, и я не слышал чтобы хоть кто-то притрагивался к доке. Ее никто даже не пытался обновлять. Почему? Потому что любая правка превращалась в квест: заполни форму, отправь на согласование, подожди две недели, пока все одобрят. Так что изменения просто игнорировали.

— Слушай, а как работает вот этот сервис? В доке же написано... — попытался спросить я коллегу, но он перебил меня громким смехом: — Забей, эту документацию писал Васян, который уволился. Он ее вообще из головы выдумал, чтобы от нас руководство отстало. Его специально и нанимали чтобы заборы красить, но он долго не протянул. Лучшая документация — это код, вот его и читай!

Так я и сделал. Разбирался, рисовал, задавал вопросы и копался в тикетах — собирал картину по кускам. Документацию больше не открывал — она была мертва и не актуальна. Но всё же она выполняла важную функцию. Она как громоотвод забирала на себя всё внимание бюрократов. Пусть подписывают, согласовывают и гордятся своим порядком. А главное — выделяют бюджеты. А мы, кто пишет код и пилит фичи, продолжим работать в параллельной вселенной.

Тогда я усвоил главный урок: если бюрократия требует жертв — дайте ей их. А сами независимо делайте так, чтобы проект жил, рос и развивался. Иногда, чтобы что-то сделать, нужно научиться работать сразу в двух несогласованных реальностях.

А проект тот мы сдали: ответственный от заказчика принял результат, нужные люди подписали нужные документы, а актуальную доку задним числом донесли через полгода.

© Счастливый тимлид